Skip to content

Show workflow code only applied signals - #436

Merged
rmcdaniel merged 4 commits into
mainfrom
general/434-applied-signals
Nov 19, 2026
Merged

rmcdaniel merged 4 commits into
mainfrom
general/434-applied-signals

Conversation

@rmcdaniel

@rmcdaniel rmcdaniel commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Fixes #434.

Behaviour

WorkflowContext::signals() used to return every SignalReceived in the history, so workflow code could act on a signal the Server had received but not applied yet, and might later reject. In the #420 cohort that closed the run before a queued update was applied.

Now a signal reaches workflow code only when one of these holds:

  • it is applied: a SignalApplied event names its signal_id or workflow_command_id, or its SignalReceived carries the workflow_sequence the Server adds once a wait has consumed it;
  • the current workflow task delivers it (resume_source_kind: workflow_signal with workflow_signal_id / workflow_command_id), since that task's completion applies it;
  • its SignalReceived names neither a signal ID nor a command ID. Imported or synthetic histories can't show application, so these stay visible as before.

Because the Server applies messages in order, an update queued before a signal is applied before workflow code can see the signal. Received-but-unapplied and rejected (SignalRejected) signals never change a new decision. Message streams keep their own cursor over every received message and are unchanged.

Replay compatibility: version marker

The applied-only view uses the standard version marker (record_version_marker / VersionMarkerRecorded) with change ID durable-workflow.sdk-php.signals-applied-only, version 1. There is no fallback and no second replay pass.

  • When it is recorded: the first time hiding an unapplied signal changes what signals() returns to a live decision. A live decision is a call at the end of the recorded history, or the predicate of a condition wait whose outcome is not recorded. The marker is sent before the commands that decision produces, and the applied-only view applies from that call on. A completed history never records it. A run that never meets an unapplied signal, or never calls signals(), records nothing.
  • Without the marker (every history recorded by earlier releases): replayed calls keep the earlier view, with every received signal visible.
  • With the marker: live decisions, and calls replayed at or after the marker's sequence, use the applied-only view. Calls replayed before it keep the earlier view, so decisions recorded before the marker replay unchanged.
  • The marker step is transparent to the authored command sequence: it is never matched against workflow commands, and its sequence is skipped.

Evidence

  • Replay fixtures, verified by scripts/ci/validate-regression-corpus.py --base-ref e62224c locally (status: pass, 3 new fixtures fail on base and pass here):
    • signals-observe-only-applied.json: a fresh run with applied, delivered-by-this-task and unapplied signals records the marker and observes only the first two.
    • signals-unapplied-legacy-history.json: no marker. A recorded decision taken from an unapplied signal replays with the earlier view, and the first live difference records the marker.
    • signals-applied-only-marker-recorded.json: marker recorded. The applied-only view explains the recorded decision, and no new marker is sent.
  • tests/AppliedSignalsTest.php covers: the WorkflowContext::signals() exposes signals the Server has not applied #434 update-before-signal ordering, rejected signals, receipt order across application kinds, a history that never reads signals replaying unchanged (no marker, no new commands), all-applied reads recording no marker, position-based selection, genuine nondeterminism reported without trying another view, and completed histories.
  • Locally on PHP 8.3.36 (capped general-sdk228-php434-* containers): full PHPUnit run, 9147 tests OK (56 skipped). PHPStan: no errors.
  • CHANGELOG (Unreleased/Fixed) and docs/sdk-reference.md describe the marker rule.

🤖 Generated with Claude Code

WorkflowContext::signals() returned every SignalReceived in the history,
including signals the Server had received but not yet applied. Workflow
code could act on a signal the Server later rejected, for example closing
the run before a queued update was applied.

A signal is now visible once it is applied (a SignalApplied event, or a
SignalReceived carrying the workflow_sequence of the wait that consumed
it), or when the current workflow task delivers it
(resume_source_kind workflow_signal). Identity-less SignalReceived records
stay visible. Message streams keep their own cursor over every message.

Replay compatibility: when hiding an unapplied signal contradicts the
recorded history, the Replayer replays again showing each signal received
before a later recorded workflow decision; signals received after the last
recorded decision stay hidden until applied. Replay fixtures cover the new
path and a legacy history.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
rmcdaniel and others added 2 commits November 19, 2026 06:13
Route the signal-compatibility retry through the existing replay() entry
instead of renaming its body, and split the applied-signal checks into
smaller functions. Behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@rmcdaniel rmcdaniel mentioned this pull request Nov 19, 2026
Replace the two-pass replay fallback with the standard version marker
durable-workflow.sdk-php.signals-applied-only. The worker records it the
first time hiding an unapplied signal changes what signals() returns to a
live decision: a call at the end of the recorded history, or the
predicate of a condition wait whose outcome is not recorded. A history
without the marker replays with every received signal visible. With it,
live decisions and calls replayed at or after the marker's sequence use
the applied-only view, and calls replayed before it keep the earlier
view. The marker step is transparent to the authored command sequence,
and runs that never meet an unapplied signal record nothing.

Replay fixtures cover a fresh run recording the marker, a history
without it, and a history with it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@sonarqubecloud

Copy link
Copy Markdown

@rmcdaniel
rmcdaniel merged commit 28c58d9 into main Nov 19, 2026
61 of 63 checks passed
rmcdaniel added a commit that referenced this pull request Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

WorkflowContext::signals() exposes signals the Server has not applied

1 participant